<!doctype html>
<html class="default no-js">
<head>
	<meta charset="utf-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
	<title>@aws/dynamodb-data-mapper-annotations</title>
	<meta name="description" content="">
	<meta name="viewport" content="width=device-width, initial-scale=1">
	<link rel="stylesheet" href="assets/css/main.css">
</head>
<body>
<header>
	<div class="tsd-page-toolbar">
		<div class="container">
			<div class="table-wrap">
				<div class="table-cell" id="tsd-search" data-index="assets/js/search.js" data-base=".">
					<div class="field">
						<label for="tsd-search-field" class="tsd-widget search no-caption">Search</label>
						<input id="tsd-search-field" type="text" />
					</div>
					<ul class="results">
						<li class="state loading">Preparing search index...</li>
						<li class="state failure">The search index is not available</li>
					</ul>
					<a href="index.html" class="title">@aws/dynamodb-data-mapper-annotations</a>
				</div>
				<div class="table-cell" id="tsd-widgets">
					<div id="tsd-filter">
						<a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a>
						<div class="tsd-filter-group">
							<div class="tsd-select" id="tsd-filter-visibility">
								<span class="tsd-select-label">All</span>
								<ul class="tsd-select-list">
									<li data-value="public">Public</li>
									<li data-value="protected">Public/Protected</li>
									<li data-value="private" class="selected">All</li>
								</ul>
							</div>
							<input type="checkbox" id="tsd-filter-inherited" checked />
							<label class="tsd-widget" for="tsd-filter-inherited">Inherited</label>
							<input type="checkbox" id="tsd-filter-externals" checked />
							<label class="tsd-widget" for="tsd-filter-externals">Externals</label>
						</div>
					</div>
					<a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a>
				</div>
			</div>
		</div>
	</div>
	<div class="tsd-page-title">
		<div class="container">
			<ul class="tsd-breadcrumb">
				<li>
					<a href="globals.html">Globals</a>
				</li>
			</ul>
			<h1> @aws/dynamodb-data-mapper-annotations</h1>
		</div>
	</div>
</header>
<div class="container container-main">
	<div class="row">
		<div class="col-8 col-content">
			<div class="tsd-panel tsd-typography">
				<h1 id="amazon-dynamodb-datamapper-annotations">Amazon DynamoDB DataMapper Annotations</h1>
				<p><a href="http://aws.amazon.com/apache-2-0/"><img src="https://img.shields.io/github/license/awslabs/dynamodb-data-mapper-js.svg?style=flat" alt="Apache 2 License"></a></p>
				<p>This library provides annotations to allow easy integration of domain classes
					with the <code>DataMapper</code> defined in <code>@aws/dynamodb-data-mapper</code>. These annotations
					are provided in a separate NPM package because they rely on two experimental
					features of TypeScript (decorators and metadata decoration) and depend on the
				<code>reflect-metadata</code> package.</p>
				<h2 id="getting-started">Getting started</h2>
				<p>To use the annotations, you will first need to enable two TypeScript compiler
					settings: <code>experimentalDecorators</code> and <code>emitDecoratorMetadata</code>. The former
					enables the use of annotations in your project, and the latter emits type
				information about declared property classes.</p>
				<p>Next, start adding <code>table</code> annotations to the domain models that represent
					records in your DynamoDB tables and attribute annotations to the declared
				properties that map to attributes of those records:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> {
    attribute,
    autoGeneratedHashKey,
    rangeKey,
    table,
    versionAttribute,
} <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-data-mapper-annotations'</span>;
<span class="hljs-keyword">import</span> uuidV4 = <span class="hljs-built_in">require</span>(<span class="hljs-string">'uuid/v4'</span>);

<span class="hljs-meta">@table</span>(<span class="hljs-string">'my_table'</span>)
<span class="hljs-keyword">class</span> MyDomainClass {
    <span class="hljs-meta">@autoGeneratedHashKey</span>()
    id: <span class="hljs-built_in">string</span>;

    <span class="hljs-meta">@rangeKey</span>({defaultProvider: <span class="hljs-function"><span class="hljs-params">()</span> =&gt;</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Date</span>()})
    createdAt: <span class="hljs-built_in">Date</span>;

    <span class="hljs-meta">@versionAttribute</span>()
    version: <span class="hljs-built_in">number</span>;

    <span class="hljs-meta">@attribute</span>()
    toggle?: <span class="hljs-built_in">boolean</span>;

    <span class="hljs-meta">@attribute</span>({memberType: <span class="hljs-string">'String'</span>})
    tags?: Set&lt;<span class="hljs-built_in">string</span>&gt;;

    <span class="hljs-comment">// This property will not be saved to DynamoDB.</span>
    notPersistedToDynamoDb: <span class="hljs-built_in">string</span>;
}
</code></pre>
				<p>Using these annotations will automatically define properties at the
					<code>DynamoDbSchema</code> and <code>DynamoDbTable</code> symbols on the class prototype, meaning
					that you can pass instances of the class directly to a <code>DataMapper</code> instance. No
					need to define a schema separately; your class&#39;s property type declarations are
				the schema.</p>
				<p>To declare a class corresponding to a map attribute value in a DynamoDB record,
				simply omit the <code>table</code> annotation:</p>
				<pre><code class="lang-typescript"><span class="hljs-keyword">import</span> {
    attribute, 
    hashKey,
    table,
} <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-data-mapper-annotations'</span>;
<span class="hljs-keyword">import</span> {embed} <span class="hljs-keyword">from</span> <span class="hljs-string">'@aws/dynamodb-data-mapper'</span>;

<span class="hljs-keyword">class</span> Comment {
    <span class="hljs-meta">@attribute</span>()
    author?: <span class="hljs-built_in">string</span>;

    <span class="hljs-meta">@attribute</span>()
    postedAt?: <span class="hljs-built_in">Date</span>;

    <span class="hljs-meta">@attribute</span>()
    text?: <span class="hljs-built_in">string</span>;
}

<span class="hljs-meta">@table</span>(<span class="hljs-string">'posts'</span>)
<span class="hljs-keyword">class</span> BlogPost {
    <span class="hljs-meta">@hashKey</span>()
    id: <span class="hljs-built_in">string</span>;

    <span class="hljs-meta">@attribute</span>()
    author?: <span class="hljs-built_in">string</span>;

    <span class="hljs-meta">@attribute</span>()
    postedAt?: <span class="hljs-built_in">Date</span>;

    <span class="hljs-meta">@attribute</span>()
    text?: <span class="hljs-built_in">string</span>;

    <span class="hljs-meta">@attribute</span>({memberType: embed(Comment)})
    replies?: <span class="hljs-built_in">Array</span>&lt;Comment&gt;
}
</code></pre>
				<h2 id="supported-annotations">Supported Annotations</h2>
				<h3 id="attribute"><code>attribute</code></h3>
				<p>Marks a property as an attribute in the mapped DynamoDB record. The annotation
					will attempt to infer the correct DynamoDB type from the TypeScript type
					metadata, though no metadata will be available for any generic type parameters
				used.</p>
				<p><code>attribute</code> must be called as a function and accepts an optional argument
				containing a partial or complete field schema definition.</p>
				<h3 id="autogeneratedhashkey"><code>autoGeneratedHashKey</code></h3>
				<p>Designates the property as representing the record&#39;s hash key. If no key is
				defined, a V4 UUID will be used.</p>
				<p><code>autoGeneratedHashKey</code> must be called as a function and accepts an optional
				argument containing a partial or complete field schema definition.</p>
				<h3 id="hashkey"><code>hashKey</code></h3>
				<p>Designates the property as representing the record&#39;s hash (partition) key.</p>
				<p><code>hashKey</code> must be called as a function and accepts an optional argument
				containing a partial or complete field schema definition.</p>
				<h3 id="rangekey"><code>rangeKey</code></h3>
				<p>Designates the property as representing the record&#39;s range (sort) key.</p>
				<p><code>rangeKey</code> must be called as a function and accepts an optional argument
				containing a partial or complete field schema definition.</p>
				<h3 id="table"><code>table</code></h3>
				<p>Designates a class as representing a table in DynamoDB.</p>
				<p><code>table</code> must be called as a function with that table name as the only argument.</p>
				<h3 id="versionattribute"><code>versionAttribute</code></h3>
				<p>Designates the property as representing the record&#39;s version attribute. The data
					mapper will use optimistic locking by incrementing the version attribute during
					<code>put</code> and <code>update</code> operations and sending a condition expression with all <code>put</code>,
					<code>update</code>, and <code>delete</code> operations that will cause the operation to fail if the
					record in the database has a version number that does not match the one held by
				the client.</p>
				<p><code>versionAttribute</code> must be called as a function and accepts an optional argument
				containing a partial or complete field schema definition.</p>
				<h2 id="caveats">Caveats</h2>
				<h3 id="reliance-on-experimental-typescript-features">Reliance on experimental TypeScript features</h3>
				<p>Because this package relies on experimental TypeScript features, it is subject
					to change and should be considered beta software. Decorators are currently on
					the ECMAScript standards track, but the accepted form may differ from that
					implemented by TypeScript, which could cause the public interface presented by
				this project to change.</p>
				<h3 id="lack-of-type-information-in-generics">Lack of type information in generics</h3>
				<p>Please note that TypeScript does not emit any metadata about the type parameters
					supplied to generic types, so <code>Array&lt;string&gt;</code>, <code>[number, string]</code>, and
					<code>MyClass[]</code> are all exposed as <code>Array</code> via the emitted metadata. Without
					additional metadata, this annotation will treat all encountered arrays as
					collections of untyped data. You may supply either a <code>members</code> declaration or a
					<code>memberType</code> declaration to direct this annotation to treat a property as a
				tuple or typed list, respectively.</p>
				<p>Member type declarations are required for maps and sets, though the member type
					will be automatically inferred if a property is declared as being of type
					<code>BinarySet</code> or <code>NumberValueSet</code> (from the <code>@aws/dynamodb-auto-marshaller</code>
				package).</p>
			</div>
		</div>
		<div class="col-4 col-menu menu-sticky-wrap menu-highlight">
			<nav class="tsd-navigation primary">
				<ul>
					<li class="globals  ">
						<a href="globals.html"><em>Globals</em></a>
					</li>
				</ul>
			</nav>
			<nav class="tsd-navigation secondary menu-sticky">
				<ul class="before-current">
					<li class=" tsd-kind-class">
						<a href="classes/author.html" class="tsd-kind-icon">Author</a>
					</li>
					<li class=" tsd-kind-class">
						<a href="classes/comment.html" class="tsd-kind-icon">Comment</a>
					</li>
					<li class=" tsd-kind-class">
						<a href="classes/post.html" class="tsd-kind-icon">Post</a>
					</li>
					<li class=" tsd-kind-interface">
						<a href="interfaces/classannotation.html" class="tsd-kind-icon">Class<wbr>Annotation</a>
					</li>
					<li class=" tsd-kind-interface">
						<a href="interfaces/propertyannotation.html" class="tsd-kind-icon">Property<wbr>Annotation</a>
					</li>
					<li class=" tsd-kind-variable">
						<a href="globals.html#metadata_type_key" class="tsd-kind-icon">METADATA_<wbr>TYPE_<wbr>KEY</a>
					</li>
					<li class=" tsd-kind-function">
						<a href="globals.html#attribute" class="tsd-kind-icon">attribute</a>
					</li>
					<li class=" tsd-kind-function">
						<a href="globals.html#autogeneratedhashkey" class="tsd-kind-icon">auto<wbr>Generated<wbr>Hash<wbr>Key</a>
					</li>
					<li class=" tsd-kind-function">
						<a href="globals.html#hashkey" class="tsd-kind-icon">hash<wbr>Key</a>
					</li>
					<li class=" tsd-kind-function">
						<a href="globals.html#rangekey" class="tsd-kind-icon">range<wbr>Key</a>
					</li>
					<li class=" tsd-kind-function">
						<a href="globals.html#table" class="tsd-kind-icon">table</a>
					</li>
					<li class=" tsd-kind-function">
						<a href="globals.html#versionattribute" class="tsd-kind-icon">version<wbr>Attribute</a>
					</li>
				</ul>
			</nav>
		</div>
	</div>
</div>
<footer>
	<div class="container">
		<h2>Legend</h2>
		<div class="tsd-legend-group">
			<ul class="tsd-legend">
				<li class="tsd-kind-module"><span class="tsd-kind-icon">Module</span></li>
				<li class="tsd-kind-object-literal"><span class="tsd-kind-icon">Object literal</span></li>
				<li class="tsd-kind-variable"><span class="tsd-kind-icon">Variable</span></li>
				<li class="tsd-kind-function"><span class="tsd-kind-icon">Function</span></li>
				<li class="tsd-kind-function tsd-has-type-parameter"><span class="tsd-kind-icon">Function with type parameter</span></li>
				<li class="tsd-kind-index-signature"><span class="tsd-kind-icon">Index signature</span></li>
				<li class="tsd-kind-type-alias"><span class="tsd-kind-icon">Type alias</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-enum"><span class="tsd-kind-icon">Enumeration</span></li>
				<li class="tsd-kind-enum-member"><span class="tsd-kind-icon">Enumeration member</span></li>
				<li class="tsd-kind-property tsd-parent-kind-enum"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-enum"><span class="tsd-kind-icon">Method</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-interface"><span class="tsd-kind-icon">Interface</span></li>
				<li class="tsd-kind-interface tsd-has-type-parameter"><span class="tsd-kind-icon">Interface with type parameter</span></li>
				<li class="tsd-kind-constructor tsd-parent-kind-interface"><span class="tsd-kind-icon">Constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-interface"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-interface"><span class="tsd-kind-icon">Method</span></li>
				<li class="tsd-kind-index-signature tsd-parent-kind-interface"><span class="tsd-kind-icon">Index signature</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-class"><span class="tsd-kind-icon">Class</span></li>
				<li class="tsd-kind-class tsd-has-type-parameter"><span class="tsd-kind-icon">Class with type parameter</span></li>
				<li class="tsd-kind-constructor tsd-parent-kind-class"><span class="tsd-kind-icon">Constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-class"><span class="tsd-kind-icon">Property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class"><span class="tsd-kind-icon">Method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class"><span class="tsd-kind-icon">Accessor</span></li>
				<li class="tsd-kind-index-signature tsd-parent-kind-class"><span class="tsd-kind-icon">Index signature</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-constructor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited constructor</span></li>
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-inherited"><span class="tsd-kind-icon">Inherited accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-protected"><span class="tsd-kind-icon">Protected accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private property</span></li>
				<li class="tsd-kind-method tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private method</span></li>
				<li class="tsd-kind-accessor tsd-parent-kind-class tsd-is-private"><span class="tsd-kind-icon">Private accessor</span></li>
			</ul>
			<ul class="tsd-legend">
				<li class="tsd-kind-property tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static property</span></li>
				<li class="tsd-kind-call-signature tsd-parent-kind-class tsd-is-static"><span class="tsd-kind-icon">Static method</span></li>
			</ul>
		</div>
	</div>
</footer>
<div class="overlay"></div>
<script src="assets/js/main.js"></script>
<script>if (location.protocol == 'file:') document.write('<script src="assets/js/search.js"><' + '/script>');</script>
</body>
</html>